Direct Sound Element

Modified on 2018/07/16 02:04 by Administrator Categorized as Auditory Stimuli, Base Elements, Elements
<div style="margin-right: 10px; margin-left: 16px; margin-bottom:10px; float: right; width: 500px; overflow: hidden; height: auto; padding: 0px; background: #fafafa; background: -webkit-gradient(linear, left top, left bottom, from(#fbfbfb), to(#fafafa));background: -moz-linear-gradient(top, #fbfbfb, #fafafa);border: 1px dashed #ddd;box-shadow: 0 0 0 3px #fff, 0 0 0 5px #ddd, 0 0 0 10px #fff, 0 0 2px 10px #eee;">
== Summary ==
{s:Element Info Panel
| title=Direct Sound
| category=Audio Stimuli
| icon=[image|Element Icon|{UP(Direct+Sound+Element)}Direct-Sound-Element-Icon.png]
| author= OkazoLab
| addin= Base Layer
| scope= Parent event
| usage= Snippets
| ownsnippets= None
}
== Properties ==
{|
|-
! Name
! Description                              
! Constraints
! Type
! On<br/>runtime<br/>change
|-
| colspan="5" bgcolor="#AADDDDD" | Settings
|-
| Sound Device        
| Selected sound device for playback        
| {s:atDesign}        
| String        
|  
|-
| Playback Mode        
| Defines the synchronization mode of the playback process. Once- a single playback synchronized with activation of the parent event, Loop- a looped playback synchronized with the parent event, Manual- a playback is initiated manually        
| {s:atDesign}        
| stPlay..        
|  
|-
| Monitor Playback        
| Defines if the element monitors the start and end playback times and is triggered at the end of the each playback        
| {s:atDesign}        
| Boolean        
|  
|-
| Test Playback        
|          
| {s:atDesign}        
| Boolean        
|  
|-
| colspan="5" bgcolor="#AADDDDD" | Sound Buffer
|-
| Buffer Type        
| Defines a type of the sound buffer created for a playback. The buffer type is determined by its location in device/computer memory.        
| {s:atDesign}        
| stDire..        
|  
|-
| Is Primary        
| If true, the element will try to allocate the primary buffer memory of the sound device for the fastest playback (exclusively for this element). The sound device has to support this option.        
| {s:atDesign}        
| Boolean        
|  
|-
| Priority        
| Defines the priority of the allocated sound buffer relatively to other buffers. The lowest priority corresponds to 0. The greater is the positive value, the higher priority is given.        
| {s:atDesign}        
| UInt32        
|  
|-
| Volume Control        
| If true, the volume of played audio can be adjusted at runtime. If false, it can improve temporal precision the playback.        
| {s:atDesign}        
| Boolean        
|  
|-
| Balance Control        
| If true, the stereophonic balance of played audio can be adjusted at runtime. If false, it can improve temporal precision of the playback.        
| {s:atDesign}        
| Boolean        
|  
|-
| colspan="5" bgcolor="#AADDDDD" | Design-time Info
|-
| Device Info        
| Information about capacities of the currently selected sound device. Click to expand all fields.        
| {s:atDesign}        
| stDSDe..        
|  
|-
| Buffer Info        
| Information about the sound buffer created for the currently selected audio clip. Click to expand all fields.        
| {s:atStatus}        
| stDSBu..        
|  
|-
| colspan="5" bgcolor="#AADDDDD" | Playback
|-
| Volume        
| Defines the volume of the audio playback, in percentages, from 0 (ground) to 100 (full)        
| {s:atNormal}        
| Int32        
|  
|-
| Balance        
| Defines the stereophonic balance of the audio playback, from 100 (most left) to 100 (most right)        
| {s:atNormal}        
| Int32        
|  
|-
| Start position        
| Defines the start position of the audio playback in percentages (0..100) to the total duration of the currently selected audio clip.        
| {s:atNormal}        
| Double        
|  
|-
| Position        
| The current playback position in percentages (0..100) to the total duration of the currently played audio. The property can be used only at runtime.        
| {s:atNormal}        
| Double        
|  
|-
| Is Playing        
| Indicates if the element is currently playing an audio. Changing this property at runtime results in toggling between the play/pause states.        
| {s:atNormal}        
| Boolean        
|  
|-
| colspan="5" bgcolor="#AADDDDD" | 3D Audio
|-
| Enable 3D        
|          
| {s:atDesign}        
| Boolean        
|  
|-
| Listener Position        
| The current 3D position of the virtual listener relatively to the fixed sound source in (0,0,0). Vector values are in the distance units.        
| {s:atNormal}        
| cl3DVe..        
|  
|-
| Front Heading        
| The current 3D orientation of the front of the virtual listener relatively to the sound source in (0,0,0). Vector values are in the distance units.        
| {s:atNormal}        
| cl3DVe..        
|  
|-
| Top Heading        
| The current 3D orientation of the top of the virtual listener relatively to the sound source in (0,0,0). Vector values are in the distance units.        
| {s:atNormal}        
| cl3DVe..        
|  
|-
| Distance Factor        
| Number of meters in the distance unit        
| {s:atNormal}        
| Single        
|  
|-
| Doppler Factor        
| The Doppler factor that has a range of 0.0 (no Doppler effects) to 10.0 (ten times the Doppler effects found in the real world)        
| {s:atNormal}        
| Single        
|  
|-
| Rolloff Factor        
| Determines the rate of the sound attenuation over distance. Has a range of 0.0 (no rolloff) to 10.0 (ten times the rolloff found in the real world).The effect is global for all Direct Sound elements        
| {s:atNormal}        
| Single        
|  
|-
| Doppler Velocity        
| Listener's velocity that is used for generation of the Doppler effect, in the distance units per second        
| {s:atNormal}        
| cl3DVe..        
|  
|-
| colspan="5" bgcolor="#AADDDDD" | Runtime Status
|-
| Start Time        
| If [Monitor Playback] property is true, this property stores the actual event time when the last playback started        
| {s:atStatus}        
| clTime        
|  
|-
| End Time        
| If [Monitor Playback] property is true, this property stores the actual event time when the last playback ended        
| {s:atStatus}        
| clTime        
|  
|-
| Is Triggered        
| If [Monitor Playback] property is true, this property indicates if the element has been triggered at least once after activation of the parent event. Triggering occurs each time when the playback ends.        
| {s:atNormal}        
| Boolean        
|  
|-
| colspan="5" bgcolor="#AADDDDD" | Material List
|-
| Selected Index        
| Defines an index of the active item in the material list of this element        
| {s:atNormal}        
| Int32        
|  
|-
| Selected Item        
| Defines a name if the active library item in the material list of this element        
| {s:atNormal}        
| String        
|  
|-
| Item Count        
| Returns the total number of material items in the list of this element        
| {s:atStatus}        
| Int32        
|  
|-
| colspan="5" bgcolor="#AADDDDD" | Control
|-
| Is Enabled        
| If set to false the element is completely omitted when the experiment is run        
| {s:atDesign}        
| Boolean        
|  
|-
| Title        
| Title of the element        
| {s:atDesign}        
| String        
|  
|-            
|}
== ==
</div>
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
'''Direct Sound Element''' is capable of playing audio clips in the wave format via DirectSound API. The element is recommended for Windows XP and old sound cards, when temporal accuracy is important. The elements allows deep tuning of playback process, if it's supported by a sound card and drivers.{br}{br}
{TOC}

== Description ==

The DirectSound element is capable of playing audio clips in the Waveform Audio File Format (WAV) via a fast, low-level interface to sound cards called [http://en.wikipedia.org/wiki/DirectSound|Microsoft DirectSound]. The element allows the fine tuning of sound hardware and playback modes. As a result very good temporal precision of audio playback can be achieved in experiments, especially when a sound hardware and drivers are fully compatible with the Direct Sound interface.

The element may have problems reading the compressed Wave files. For better results, the uncompressed PCM format is preferred.

Like other audio elements in EventIDE, the Direct Sound element allows full control of of the playback process: mixing of multiple sounds, changes in sound volume, panning and playback position.

In addition, the element allows an easy management of 3D sound features, e.g. adjusting the 3D surround mapping via coordinates of listener's position in a virtual 3D space.

== Snapshots ==

{|
| [imageleft||{UP(Direct Sound Element)}DirectSoundEl_sm.jpg|{UP(Direct Sound Element)}DirectSoundEl.png]
|}


== When to use the DirectSound element ==

EventIDE provides several [elements|elements] for delivering auditory stimuli. The audio elements have similar functionality and a choice depends on design demands and the used sound hardware. A guidance on selecting an audio element is available in [Auditory Stimuli] article.

In short, the DirectSound element is best for Windows XP systems with old-fashioned hardware cards that have an on-board memory or when precise hardware tuning is necessary.

== Stimulus Set ==

The element can be easily adapted to make up an audio stimulus set that contains multiple audio clips. Then one of these clips can be selected to be played in the given trial.
To make a stimulus set, load selected audio clips from [Material Library] directly into the element (e.g. by drag and drop). Then use the Item Index property to select an audio clip for playback. It's recommended to change the Item Index property before the onset of the parent event because preparing the clip for playback takes some time.

== Practical Use ==

# Add a new Direct Sound element into the selected event (where an audio has to be played).
# Select the element in the [Element panel], then its properties will appear in the [Property panel] at the right.
# Load selected audio clips from the Material Library to the item list of the element and select the current clip via Item Index property.
# Browse to the settings group in the element properties and select a sound device from a list of the available hardware.
# Select a playback mode for the give element via the corresponding property. The common mode for presentation of auditory stimulus is "Single playback on onset of the parent event"
# Test if an audio is played by clicking over the Test Playback property.
# Make sure that duration of the parent event is greater or equal to duration of the selected audio clip- an audio playback is always aborted on offset of the parent event.

There are two typical scenario of using the element for presenting audio stimuli in multiple trials:

* If you want to present a random audio clip in each trial, use the 'Single playback' mode and add a [Proxy Variables|proxy] linked to the Item Index property. With that proxy you can select an audio clip from the element's list in code snippets (normally before onset of the parent event)
* If you want to chose whether an audio clip has to be played or not in each trial, select 'Manual' mode add a [Proxy Variables|proxy] linked to the Is Playing property. Setting that proxy to true/false in code snippets will allow to turn on/off audio playback on the onset of the parent event (the proxy has to be set before the event onset).


=== Playback modes ===

At runtime the element can work in 3 different playback modes, which define how playback process starts and stops. The mode has to be selected at design-time and cannot be changed. However, it's possible to use multiple elements working in different modes in parallel. The available modes are:

==== Single playback on onset of the parent event ====

In this mode the element starts to play an audio synchronously with the onset of the parent event. The audio is played to the end one time. If parent event is deactivated before the audio end is reached, the playback is aborted.

==== Looped playback on event onset ====

In this mode the element starts to play an audio synchronously with the onset of the parent event and keep repeating it automatically when the playback end is reached. This playback loop lasts until deactivation of the parent event.

==== Manual playback ====

In this mode the element plays an audio only via a manual request which is made by code snippets when desired. The playback is initiated by assigning true to the Is Playing property of the element. Later, the same property can be used to monitor if the audio is still currently played. Is Playing property automatically turns to false when the playback ends. At this moment and later you can initiate a new playback if the parent event is still active.

== Advanced capacities ==

The DirectSound element has a group of [properties] for fine tuning of sound hardware. There you can select the sound card among multiple sound cards installed on the same computer and set up its memory configuration for the most efficient audio playback. The element automatically collects and returns information about hardware capacities of the sound card that can be accessed by the Device Info property.
For testing purposes the element is capable of measuring its own playback time statistics,e.g. the properties Start Time and End Time can be used to estimate the offset and actual playback duration at runtime. <!--Grammar fix 2013-08-11 -->

== 3D audio ==

The DirectSound element supports the 3D audio effect widening the perceived sound image for the listener. For most realistic results using more than 2 speakers is necessary. The overall control over 3D audio effect is very simple- the element adjusts audible channels according to the position of a virtual listener relatively to a fixed sound source in 3D space. You can dynamically change the listener position at runtime, changing just 3 coordinates. In addition, you can customize the produced 3D audio with the Doppler effect and with the effect of sound attenuation over a distance. Notice, that you have to provide a mono wave clip for playback if 3D audio is enabled (by the Enable 3D property)

== Performance notes ==

In general, the temporal accuracy of the DirectSound playback is always traded for requested controls over the playback process. For example, you may get more accurate timing if you decide not to change the sound volume during playback. The DirectSound element allows you to choose only controls that are currently necessary. Set the properties [Volume control], [Balance control], [3D enable], [Triggering] to False in order to get better temporal performance. In addition, you can manually set up the memory management for playing sound. If the sound card supports it, try to allocate the memory buffer for an audio in the hardware memory of the sound card by setting the [Buffer type] property. If you have a single auditory stimulus delivery in your experiment, you can try to use the Primary buffer of the sound card for a single DirectSound element (the [Primary Buffer] property) - it should give you even better playback performance. Using audio clips of uncompressed formats, like WAVE PCM, with the sample rate and other characteristics matching to the format of the sound card memory buffers can also greatly improve the playback performance.

== Triggering at the end of the playback ==

Sometimes it's necessary to abort the parent event immediately after the playback has reached its end. Since the Wave Player element can contain multiple audio clips of different durations, the duration of the parent event can not set to fix value. The wave player elements offers an easy solution - it monitors the playback process and gets triggered at the end of each audio clip. Triggering causes a call of the OnTriggered snippet that can be used for user actions. In addition, the element has a boolean property, called Is Triggered, which can be used directly (as [Proxy]) in controlling the event flow.

== Notes ==

*The Direct Sound element is optimized to deliver the best timing accuracy of the audio playback. However, it's always recommended to measure empirically the timing of the actual playback when high accuracy is required. The measurements can be done with oscilloscope connected to the output of the sound card. Probing different settings of the element can help to achieve the optimal results.
*The DirectSound interface get a direct access to sound hardware only in Windows XP. It is NOT the case for Windows Vista/7/8, where DirectSound works in the software emulation mode. Although such emulation can be very efficient, the temporal precision of sound playback with DirectSound element can be lower under Windows Vista/7/8 and using Wave Player Element is recommended.
*If 3D audio feature are enabled, only mono audio clips have to used with the element.
*Slightly better onset of the audio playback can be achieved if the element is placed at the top of the elements list in the parent event. Elements in the list get activated one by one on the onset of the parent event, so the top position in the list will minimize the onset delay.
Meta Keywords:
Meta Description:
Change Comment:
EventIDE Wiki

Navigation¶

Direct Sound Element
